Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / UTILITY / AUTRD109.ARJ / MANUAL.DOC < prev next >

Wrap

Text File | 1990-10-11 | 70KB | 1,743 lines

┌────────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ AUTOREAD │ │ │ │ A program to allow easy reading of large text files │ │ on a computer │ │ │ │ Author: David R Grigg │ │ │ │ Version 1.08 │ │ October 1990. │ │ │ │ │ │ │ │ MANUAL │ │ │ │ │ │ (C) Copyright David R Grigg, 1990 │ └────────────────────────────────────────────────────────────────┘ AUTOREAD Manual -1- 1: IMPORTANT NOTICE! ═══════════════════════════════════════════════════════════════════════ If you are reading this file on your computer in any other way than using AUTOREAD itself, then you are losing out on the value of AUTOREAD, and you will also not be able to try out the software as you follow the examples given later in this document. To read this document using AUTOREAD, go back to DOS and type: AUTOREAD MANUAL <and press the enter key>. DISCLAIMER ────────── While every effort has been made to free AUTOREAD from errors, and I can't imagine how AUTOREAD could cause you any problems, as a matter of prudent legality, please heed the following notice: I, David R Grigg, accept NO RESPONSIBILITY OR LIABILITY for any damage that may be caused to your computer, disks or data by the use of AUTOREAD. If this makes you nervous, try AUTOREAD out on a floppy disk first. As a matter of good practice you should always keep regular backups of important files. AUTOREAD Manual -2- 2: Introduction ════════════════════════════════════════════════════════════════════════ I wrote this program because I often find myself in the situation of having a large text file on my computer's hard disk which I am using because it has some kind of information of value to me. Usually it is the manual for a shareware program. I adore shareware. I think the concept of trusting people to pay a modest fee for software they genuinely find useful is terrific. And I use a lot of shareware (and pay the appropriate registration fees). But the manuals for most shareware programs are distributed as a text file unless you pay extra (and I generally don't). So I end up with very useful manuals in a very NON-useful form: a large text file on my hard disk. Sure, I can print out the manual, but this can consume enormous amounts of time, paper and printer ribbons (the QEDIT manual, for example, is some 5500 lines long). And besides, I can never find the manual when I want it. And even if I can, finding the information I want can be very hard. Aren't computers supposed to make life easier? Yet reading a document on a computer screen is still extremely primitive. Certainly you can use a useful utility like LIST, but this is still missing something. It's hard to navigate around in a large text file, to find the next chapter, or to locate key words. Using the FIND utility in such programs is some help, of course, but you have to type in the key word, and hope you have spelt and punctuated it properly. AUTOREAD is my attempt to fill this perceived gap. It works very much like LIST, but it allows you to progressively establish landmarks in the text and to go instantly to them. AUTOREAD allows the creation of several kinds of 'landmarks': * Chapter Stops * Pre-defined Keywords * Temporary Bookmarks These are all available via pull-down menus for easiest possible use. What all this means is that you can very easily create a comprehensive index to a particular text file, enabling you to instantly find the section or information you are looking for. It makes reading a text file on your computer as easy as reading a hard copy, and in some respects easier. AUTOREAD Manual -3- 3: Shareware Notice ══════════════════════════════════════════════════════════════════════ AUTOREAD took a lot of effort to create. And I am still working on improving it. Please note that AUTOREAD is not, never has been, and never will be free or public domain software. It is shareware. The shareware concept is extremely simple. If you obtain a copy of a shareware program, find it useful to you, and wish to continue using it, you must send the requested shareware fee to the program author. Shareware relies entirely on trust. But it is a concept which has allowed the creation and distribution of a large body of excellent software at very low cost. If you find AUTOREAD of use, please print out and fill in the enclosed LICENSE.DOC document, and send it with the requested $20 shareware fee to: David R Grigg, 1556 Main Road, Research, Victoria 3095 Australia. NOTE: Most commercial software forbids you to make copies of it. But because AUTOREAD is shareware software, you are positively ENCOURAGED to share copies of AUTOREAD around, copy it for your friends, upload it to bulletin boards, etc. The only stipulations are that all those who use AUTOREAD for longer than a trial period of 14 days must pay the required shareware fee, and that AUTOREAD must be distributed with all the associated files, being: AUTOREAD EXE LICENSE DOC MANUAL ARD MANUAL DOC MANUAL ARI README BAT CHAPMAKE EXE STATS DOC STATS EXE AUTOREAD Manual -4- 4: Installing AUTOREAD ══════════════════════════════════════════════════════════════════════ AUTOREAD is extremely easy to install. The only file absolutely necessary to operating AUTOREAD is AUTOREAD.EXE, which you should copy either into the same directory as the documents you wish to use it on, or (especially if you have a hard disk) into a directory which is listed in your DOS PATH command (this is usually specified in your AUTOEXEC.BAT file). Many hard disk users have a directory called \TOOLS on their hard disk. This is a good place for AUTOREAD. To use AUTOREAD on a particular text file (as an example, say a file called MANUAL.DOC), you would enter the following at the DOS prompt: AUTOREAD MANUAL.DOC If you don't enter the file name, you will be prompted for it. NOTE: If you don't enter a file extension (eg the .DOC above), then AUTOREAD will attempt to find a file with the name you have given it, with either of the following extensions: .DOC .TXT If it still can't find the file, it will give up with an error message. AUTOREAD Manual -5- 5: Files Created by AUTOREAD ══════════════════════════════════════════════════════════════════════ AUTOREAD maintains two different files of its own for every text file that you use it on. If you used it on a document called MANUAL.DOC, for example, AUTOREAD would create the following files: MANUAL.ARI MANUAL.ARD Unless you have changed the textfile since you last read it, the .ARI file will be created only the first time you use AUTOREAD on the text file. The .ARD file, however, is constantly read and rewritten. The .ARI file is an index of the starting points of each line of the text file, and enables AUTOREAD to very speedily locate parts of the file. If it offends you to have a lot of additional files in a directory, you can delete this file, but then AUTOREAD will need to recreate it each time you access the text file that it indexes. The .ARD file contains such data as the current location in the file, a list of chapter stops and their starting lines, and a list of keywords. Note that the .ARD file is an ordinary text file, which means that you can use a text editor to manipulate it directly. NOTE: If you just wish to use AUTOREAD quickly on a small file you wish to look at but will probably never wish to fully index and set up chapter stops on, you can append an option, -Q, to the command line, eg: AUTOREAD MANUAL.DOC -Q This ensures that AUTOREAD will get rid of its .ARI file on exit, and will not access or create an .ARD file. NOTE: Users of AUTOREAD 1.01 should not that the index file extension has been changed from the previous .IDX to the current .ARI (this was to avoid possible conflicts). If you have already created an .IDX file for a large document, all you need do is to rename it; or alternatively to delete it and let AUTOREAD recreate the index. AUTOREAD Manual -6- 6: The AUTOREAD screen ══════════════════════════════════════════════════════════════════════ If you are using AUTOREAD to read this manual, you are already in the default screen mode - Display Mode. 6.1 Display Mode ────────────────────────────────────────────────────────────────── This is the DISPLAY mode of AUTOREAD. Note the top line, in reverse colours, which indicates that you can press the ESCAPE or ESC key to bring up the AUTOREAD Menu Bar, or hold down the ALT key and then the press the X key on your keyboard to exit AUTOREAD. NOTE: It is important to exit AUTOREAD in the standard way, by pressing Alt-X. Doing this saves important information such as any chapter stops, and new keywords you may have created. If you exit in any other way (ie, by simply turning off the computer, or by rebooting), this information will not be saved. Despite the above, from version 1.08 onwards, I've added the Alt-Q function, which lets you quit without saving the above data, although you are prompted first. This is for those who KNOW they haven't created any new information, and prefer to avoid an unnecessary disk access. Use with caution! At the bottom line of the screen you will see information on the current line number, the current search direction, and the pathname of the file being read. 6.2 Menu Mode ───────────────────────────────────────────────────────────────── Pressing ESC changes the top line of the screen to a Menu Bar. See the section on The AUTOREAD Menu Bar for further information. AUTOREAD Manual -7- 7: Moving Around in Your Document ══════════════════════════════════════════════════════════════════════ The up and down arrow keys on your keyboard will scroll the text on your screen in the indicated direction. Pressing PAGE UP on your keyboard will move to the previous screen-full of information. (Unless you are at the start of the file, of course). Pressing PAGE DOWN on your keyboard will move to the following screen-full of information. (Unless you are at the end of the file, of course). Holding down the Control (CTRL) key on your keyboard and pressing HOME will go to the start of the file. Holding down the Control (CTRL) key on your keyboard and pressing END will go to the end of the file. It is also possible to move to specific areas of the file by using the AUTOREAD menu bar (see next section). 7.1 Crawl Read ───────────────────────────────────────────────────────────────── Pressing any of the number keys (0..9) on the keyboard will start the display crawling forward slowly, ideally at a comfortable reading speed. How fast the display crawls will depend on the number you typed: 0 for the slowest crawl, 9 for the fastest. While you are in crawl mode, you can adjust the speed of crawl by pressing another number key, or stop the crawl and carry out some other function by pressing any key other than one of the number keys. AUTOREAD Manual -8- 8: The AUTOREAD Menu Bar ══════════════════════════════════════════════════════════════════════ You can call up the AUTOREAD menu bar simply by pressing the Escape (ESC) key on your keyboard. The top line of your screen will alter to show a series of menu choices, like this: ┌────────────────────────────────────────────────────────────────────────┐ │ AUTOREAD: Go Chapter Keyword Mark Find Screen Dump ??? │ └────────────────────────────────────────────────────────────────────────┘ The first entry will be highlighted. You can move the highlight by pressing the left and right arrow keys on your keyboard. When the entry you want is highlighted, press the ENTER key on your keyboard, and a sub-menu will appear. Alternatively, you can simply press the first letter of your menu choice, and the sub-menu will immediately appear. To activate the Keywords sub-menu, for example, simply press the 'K' key on your keyboard. What follows is a brief description of each of the sub-menus and what they do. More detailed explanations are in following chapters. 8.1 Go ───────────────────────────────────────────────────────────────── The Go menu allows you to move quickly to different positions in the file: the beginning, the middle, the end, or to a specific line number. From Version 1.06, this menu also allows you to search for page numbers in the document; this requires setting a 'template' for how the document author has marked page numbering. See Chapter 9 for more information. 8.2 Chapters ───────────────────────────────────────────────────────────────── This is perhaps the most powerful part of AUTOREAD. This menu allows you to find instantly any one of up to 500 'chapter stops', by selecting a description from a pull-down menu. They are called 'chapter stops' because the idea is that you can set up such stops at the beginning of chapters or major sections in the document. This menu allows you to find, create, delete or change an existing chapter stop. It also allows you to clear all existing chapter stops, or to automatically make chapter stops at standard points in a document. 8.3 Keywords ───────────────────────────────────────────────────────────────── An AUTOREAD keyword is like a FIND command for pre-defined strings. It means you can create a list of common or AUTOREAD Manual -9- especially important words, perhaps from the index of the manual, and quickly point to them. Once you have chosen a keyword to find, AUTOREAD will quickly scan the file looking for the next occurrence of that keyword. Note that you can alter the direction of the search from this menu. This menu allows you to find, create, or delete keywords. 8.4 Marks ───────────────────────────────────────────────────────────────── 'Marks' is short for 'bookmarks'. They work in a very similar way to chapter stops, except that they are temporary (they vanish when you exit AUTOREAD), and the listing entries simply give the bookmark number and the line number, rather than a description. Bookmarks are intended as a quick way of placing a marker in the text while you look for some other information, and then being able to quickly return to where you left off. Note also that when you exit AUTOREAD, the current position in the file when you exited is stored, so that the next time you use AUTOREAD to read the file, the screen will be the same as when you exited the previous time. 8.5 Find ───────────────────────────────────────────────────────────────── This menu lets you search for any text (not a pre-defined keyword). You can specify the direction of search from this menu. 8.6 Screen ───────────────────────────────────────────────────────────────── This menu allows you to set the foreground colour and background colour of the text on the screen, as well as the colour of highlighted text. 8.7 Dump ───────────────────────────────────────────────────────────────── This lets you dump parts of the document you are reading to another file, or to the printer. You can select the section you wish to dump as just what is on the screen, the current chapter or section, or a specified range of lines. AUTOREAD Manual -10- 8.8 ??? ───────────────────────────────────────────────────────────────── Choosing this option will bring up an information screen about AUTOREAD. It is not a help screen (limited help is available by pressing F1 in Display Mode. AUTOREAD Manual -11- 9: Go Menu ══════════════════════════════════════════════════════════════════════ The Go Menu looks like this: ┌───────────────┐ │ Top ^Home │ │ Middle - │ │ End ^End │ │ ------------ │ │ Line Number │ │ ------------ │ │ Page Number │ │ Odd Page Set │ │ Even Page Set │ │ Search DOWN │ └───────────────┘ Move the highlight around with the up and down arrow keys. When it is on the selection you want, press ENTER on the keyboard. Alternatively, simply enter the first letter of your choice. You will note next to some of the entries their 'short forms', eg for Top you will also see ^Home. This means that you can enter the short form and have the action take place immediately without needing to call up the AUTOREAD Menu Bar. In other words, to go to the top (or start) of a file, you can either press ESC to get the Menu Bar, then G for the Go Menu, then T for top, or simply press down the Control Key on your keyboard and then the HOME key. This first four choices on the menu should be self-explanatory: 9.1 Top (^Home) ───────────────────────────────────────────────────────────────── Goes to the start of the file. 9.2 Middle ───────────────────────────────────────────────────────────────── Goes to the very middle line of the file. 9.3 Bottom (^End) ───────────────────────────────────────────────────────────────── Goes to the end of the file. 9.4 Line Number ───────────────────────────────────────────────────────────────── Lets you enter and go to a particular line number in the document. AUTOREAD Manual -12- 9.5 Page Number ───────────────────────────────────────────────────────────────── From version 1.06, I have added the very valuable function of being able to search for particular page numbers in the document. This is very useful if the document comes with a contents page and index page which shows these page numbers. Searching for a page number is not as easy as it might sound, however, because simply looking for a number such as say 25 will locate many erroneous instances of the number which are not page numbers. So AUTOREAD requires that you set a 'template' for what the page numbering looks like in the document. Fortunately, this is very easy for the user, and is described in the following two sub-sections. Once you have created the template for a particular document, you will never need to do it again, as AUTOREAD writes the template(s) to the .ARD file. This may all sound complex. However, FINDING a page once the template is set could not be easier. Simply choose Page Number from the Go Menu, and then enter the desired page. Note that you can enter such constructs as '2-25' with no problems. AUTOREAD then does a text search for the desired page, checking instances of the number against its template. NOTE: Page find is far from perfect. Its success will depend on the consistency of the way the manual author has set up page numbering. 9.6 Odd Page Set ───────────────────────────────────────────────────────────────── To set up the page numbering template for odd pages, position the document so that a line containing an odd page number is at the top of the display screen. Eg, in the Telix manual, I positioned a line like this as the current line (unless you have set a Screen Offset, this will be the top line of the screen): ┌─────────────────────────────────────────────────────────┐ │Telix v3.12 5 │ └─────────────────────────────────────────────────────────┘ You will need to do this positioning in Display Mode, and then hit ESC, G and choose Odd Page Set from the menu. You will be asked what the embedded page number is - in the example given it was 5. With numbering of the form 2-5, you should enter this whole construct, ie 2-5, not just 5. That's all there is to it. AUTOREAD Manual -13- NOTE: AUTOREAD assumes that Even Numbered pages are identical to Odd Numbered pages unless told otherwise. So if they are different (eg, even pages have number at the left of screen), be sure to set Odd FIRST, then set Even. NOTE: Avoid positioning on a page whose number is embedded in other text on the line, eg, in the example given above it would have caused problems to position on line 3,1,2 or 12, as these numbers are all embedded in the 'Telix v3.12' string. 9.7 Even Page Set ───────────────────────────────────────────────────────────────── This is identical to Odd Page Set, except you should position the current line to an EVEN numbered page. You only need to do this if the format for even pages is different from that for odd pages. 9.8 Search Direction ───────────────────────────────────────────────────────────────── This allows you to determine the direction in which AUTOREAD will search in looking for page numbering. The default is DOWN, ie to line numbers following the current line. UP searches to decreasing line numbers from the current line. GLOBAL searches from beginning of file. To toggle the direction, simply select this choice. AUTOREAD Manual -14- 10: Chapters Menu ══════════════════════════════════════════════════════════════════════ The Chapters Menu looks like this: ┌────────────┐ │ Find F2 │ │ Add F7 │ │ Edit │ │ Delete │ │ Sort LINE │ │ ---------- │ │ Clear │ │ Remove │ │ Make │ └────────────┘ As indicated earlier, 'Chapter Stops' are perhaps the most powerful part of AUTOREAD. You can use it to move instantly to the beginning of various chapters or sections within the text file. This menu allows you to find instantly any one of up to 500 'chapter stops', by selecting a description from a pull-down menu. The Chapters Menu also allows you to add, change and delete such chapter stops, as described below: 10.1 Find (F2) ───────────────────────────────────────────────────────────────── This brings up a menu of the existing chapter stops. You can move the highlight to the wanted chapter stop by using the up and down arrow keys. Note that if there are enough chapter stops, the listing will scroll up and down within the box. You can also use PAGE UP and PAGE DOWN to move through the listing. Once you have selected your desired chapter stop, press ENTER, and the screen will immediately fill with the text starting at the desired chapter stop. 10.2 Add Current (F7) ───────────────────────────────────────────────────────────────── This allows you to set the current line (that is, the line currently at the top of the display screen) as a chapter stop. If you make this choice from the Chapters menu, you will be prompted for a description. However if you use the F7 key from Display Mode, there are no prompts - the computer will make a warbling sound to show that it has captured the current line. 10.3 Delete ───────────────────────────────────────────────────────────────── This will allow you to get rid of a particular chapter stop, which you identify from the same pull-down menu as for the Find function. You will be prompted to confirm the delete. AUTOREAD Manual -15- 10.4 Edit ───────────────────────────────────────────────────────────────── This will allow you to edit the description of a particular chapter stop, which you identify from the same pull-down menu as for the Find function. Note that in this version of AUTOREAD, Edit does not allow you to alter the line number of a chapter stop. 10.5 Sort on LINE or ALPHA ───────────────────────────────────────────────────────────────── When you see the pull-down menu of chapter descriptions, the default is for these to be listed in line number order, ie, sequentially through the document. For shareware manuals, this is almost certainly the way you will want it. However, there may be instances where it would be useful to have these descriptions listed in alphabetical order, and so I have provided the capability to do this. To toggle the chapter descriptions into alphabetical order, simply select the Sort choice from the chapters menu. The order shown toggles from LINE to ALPHA and back again each time you select this choice. 10.6 Clear ───────────────────────────────────────────────────────────────── This allows you to get rid of ALL current chapter stops. Please use this carefully! You will be prompted to confirm the clear. 10.7 Remove (Duplicates) ───────────────────────────────────────────────────────────────── This will remove duplicate chapter stops, that is, it will remove the second and further instances of a chapter stop referring to the same line of the document. This can be useful when cleaning up after a series of Makes (see below). 10.8 Make ───────────────────────────────────────────────────────────────── This is an extremely powerful utility, which allows you to AUTOMATICALLY create chapter stops from various kinds of clue in the text of the document. If you choose Make, you are taken to a sub-menu, which looks like this: ┌────────────┐ │ Textual │ │ Procedural │ │ UpperCase │ └────────────┘ These options are each described in the following sections. AUTOREAD Manual -16- Note: you can run any form of Make repeatedly on a file to identify different levels of sections. New chapter stops do not overwrite existing ones, but are inserted in correct document order. 10.9 Textual Make ───────────────────────────────────────────────────────────────── Textual make is the most secure form of the Make command, but will only work for documents where the document author has used a standard way of identifying chapter or section beginnings. Texutal Make allows you to scan the whole document, looking for a designated string of text, and setting a chapter stop once it has found it. It is possible to set a line offset from the searched for text, and a prefix for the description. An example will make this easy to understand. 10.9.1 A Textual Make Example One of the first documents I used AUTOREAD on myself was the manual for the excellent shareware text editor QEDIT. This manual is some 5500 lines long. The document author had used a line of equal signs '====' to underline each chapter heading, and a graphic line '────' to underline each section heading. I first made a pass with Textual Make, searching for the line of equal signs. Once I selected Textual Make, I was prompted for the text string to search for. I entered four equal signs, =====. I was then prompted for a line offset. This allows you to specify a line OTHER than the one on which the text string was found as the actual chapter stop. In my case, since the wanted line was the line immediately ABOVE the line of equal signs, I entered an offset of -1. (If I had wanted the line of equal signs itself, I would have entered 0). I was then prompted for a prefix string. The real value of this is for sections or sub-sections, so I simply pressed ENTER instead of entering a prefix. The program then took about 30 seconds to scan through the whole QEDIT document and set up the chapter stops. AUTOREAD took the first text on the line I indicated I wanted the chapter stop on, and used this as its description for that chapter stop. I then wanted to set up sections as chapter stops, so I carried out another pass with Textual Make. AUTOREAD Manual -17- Once I selected Textual Make, I was prompted for the text string to search for. I entered four graphic line characters, '────'. (I used the ALT key and the numeric keyboard to enter these characters - refer your DOS manual if you don't know how to do this). I was then prompted for a line offset. As again the wanted line was the one above the graphic line, I entered an offset of -1. I was then prompted for a prefix string. I now wanted to use this feature, to distinguish the section headings from the chapter headings in the Find Chapter pull-down menu. So I entered a hyphen and a space, '- '. These characters were placed before the description for all the chapter stops created during this Make pass. Another 30-40 seconds, and I had essentially the equivalent of the contents page of the manual in the form of a pull-down menu. Here is part of the chapter stops menu I created for QEDIT.DOC: ┌──────────────────────────────────────────┐ │ - COLORS │ │ - TABLE OF CONTENTS │ │ - ACKNOWLEDGEMENTS │ │ - INTRODUCTION │ │ - FEATURES │ │ - SYSTEM REQUIREMENTS │ │ - INSTALLATION │ │ CHAPTER 1. USERS GUIDE FOR QEDIT │ │ - QUICK START │ │ - MENUS │ │ - THE STATUS LINE │ │ - FILES │ │ - VIEWING AND GETTING AROUND IN THE TEX │ │ - CURSOR MOVEMENT │ │ - USING WINDOWS │ └──────────────────────────────────────────┘ If you are using AUTOREAD on a document you are editing, then I recommend the use of the stand-alone Make utility, described below. Note that the means of designating chapter stops need not be types of underline, as in the example above, but could be the word CHAPTER in capitals (Note that Make distinguishes between upper and lower case, unlike Find Text and Find Keyword), or a special character or series of characters (eg ---> ). The best way to learn how Make works is to try it out. Don't worry about making mistakes, you can always Clear and start again. AUTOREAD Manual -18- 10.10 Procedural Make ───────────────────────────────────────────────────────────────── I added this function after I had been using AUTOREAD myself on quite a number of different shareware manuals. While the textual make function works very well for manuals where the author has used some standard form of underlining or text identifying the start of chapters and sections, it proves awkward for instances where the author has only used section numbering of the 'procedural' form, ie: 1.0 INTRODUCTION 1.1 Hello 1.2 Goodbye 1.2.1 Farewell 1.2.2 Cheerio. So I added this function. Selecting Procedural Make will result in you being prompted for whether the section numbering is numeric or alphabetic (some authors have appendixes sectioned off in the form: A.1, A.2, B.1, etc). Once you have made this choice, the program takes over. If numeric sectioning was chosen, then AUTOREAD will indentify as a chapter stop any line whose first text was a number, and if that number was followed by a period (.) before any other character. It will also count the number of periods in the section number, and indent the description appropriately. If alphabetic sectioning was chosen, then AUTOREAD will identify as a chapter stop any line whose first character was an uppercase letter and whose second character was a period. 10.11 UpperCase Make ───────────────────────────────────────────────────────────────── I added this form of Make when I discovered that there were manuals (PKZIP is a good example) where the ONLY indication of a chapter or section heading was that the heading was all in upper case (capitals). UpperCase Make works by checking each line of the document to see if it is all in uppercase. At least the LAST THREE non-blank characters in the line must be uppercase letters. Any line meeting these requirements will be identified as a chapter stop. 10.12 Problems with Make ───────────────────────────────────────────────────────────────── Almost inevitably, with any of the above forms of Make, you will end up with some invalid chapter stops. You can either use the Delete function from the Chapter menu to remove these, or edit the .ARD directly (See Appendix C). One particular trap with Procedural Make is Contents Pages. AUTOREAD Manual -19- AUTOREAD naturally cannot tell the difference from a section heading in the body of the text and that heading repeated in the Contents Page. If you can edit the original document, it is useful to simply insert some character other than a space or a number in the left hand margin of the Contents Page, BEFORE you do the Make. This prevents AUTOREAD from seeing these section headings. If you can't edit the original document for some reason, you will just need to tidy up the .ARD file manually. UpperCase Make is very subject to erroneous entries, because all it has to go on is a line which is all in capitals. You will almost certainly need to do some weeding with this form of Make. Also, the requirement that the last three characters be uppercase letters (not numbers or symbols) means that some headings may be missed if they end with a period or a number. 10.13 The Stand-Alone Make Utility ───────────────────────────────────────────────────────────────── Particularly for the use of shareware authors who might like to distribute a special version of AUTOREAD with their shareware manuals (see Chapter 16), I have provided a stand-alone chapter make utility, CHAPMAKE.EXE. This is also useful to anyone using AUTOREAD on a document which for whatever reason has to be altered regularly. The advantage of this utility is that it allows you to set up an automated chapter make which you can run each time you have make a significant change to your manual or other document you wish to use AUTOREAD on. To run CHAPMAKE, enter a command line such as the following: CHAPMAKE MANUAL However, you must first create a text file with the make commands in it. This file normally has the same name as the document you'll use AUTOREAD on, but with an extent of .MAK. So if your document is called MANUAL.DOC, then the make file will be called MANUAL.MAK. Note however that you can optionally use a standard make file by including its name on the command line, eg: CHAPMAKE MANUAL STANDARD.MAK This has the advantage of being able to use a single standard make file for several different manuals. The make file can have any number of command lines. There are only currently 4 commands, described as follows: 10.13.1 C - Clear Chapters A line with the character 'C' at its start will clear all existing chapter stops, just as if you had selected Clear from the Chapters Menu. Note that any existing keywords are left untouched. AUTOREAD Manual -20- 10.13.2 T - Textual Make A line starting with 'T' has the effect of a Textual Make command as selected from the Chapters Menu. The 'M' must be followed by the text to search for, the line offset, and the prefix, all separated by slashes (/). These are exactly as you would enter them in the menu-driven make utility within AUTOREAD. For example, take the following line: T/ ══════/-1/* / │ │ │ │ │ │ │ └─ Prefix │ │ └─ Line Offset │ └──────── Text to find └───────────── Textual Make command This line in the make file would set up as chapter stops the lines preceding the text ' ══════', and would prefix the description with '* '. 10.13.3 N - Numeric Procedural Make A line beginning with 'N' acts exactly as if you had chosen Procedural Make from the Chapters Menu, and then selected Numeric section numbering. 10.13.4 A - Alphabetical Procedural Make A line beginning with 'A' acts exactly as if you had chosen Procedural Make from the Chapters Menu, and then selected Alphabetic section numbering. 10.13.5 U - UpperCase Make A line beginning with 'U' acts exactly as if you had chosen UpperCase Make from the Chapters Menu. 10.13.6 R - Remove Duplicates A line beginning with 'R' acts exactly as if you had chosen Remove from the Chapters Menu. 10.13.7 Example Make File: This is the Make file I use for the AUTOREAD manual: ┌───────────────────────────┐ │ C │ │ T/ ═══════/-1 │ │ T/ ───────/-1/-- / │ │ R │ └───────────────────────────┘ AUTOREAD Manual -21- 11: Keywords Menu ══════════════════════════════════════════════════════════════════════ A keyword is simply a text string to be found in your document, and the Find Keyword function works exactly as does the Find Text function, except that you don't need to type in the required text: you simply select it from a pull-down menu. The Index of a document is a great place to find useful keywords. The Keywords Menu looks like this: ┌──────────────┐ │ Find F3 │ │ Add │ │ Delete │ │ -------- │ │ Search DOWN │ └──────────────┘ 11.1 Find (F3) ───────────────────────────────────────────────────────────────── This brings up a menu of the existing keywords. You can move the highlight to the wanted keyword by using the up and down arrow keys. Note that if there are enough keywords, the listing will scroll up and down within the box. You can also use PAGE UP and PAGE DOWN to move through the listing. Once you have selected your desired keyword, press ENTER, and the screen will begin searching in the indicated direction for the wanted keyword, putting up a display of the current line number being searched. If the keyword cannot be found, an error message will appear. Note that unlike the Chapter Make command, Find Keyword IGNORES the difference between upper and lower case. That is, 'DOS', 'Dos' and 'dos' will all be found by the same keyword choice. Once the keyword is found, you will be dropped back to Display mode, with the first occurrence of the wanted keyword on the top line, and all occurrences of the keyword on the current screen will be highlighted in the current highlight colour. 11.2 Add ───────────────────────────────────────────────────────────────── This prompts you for the text of a new keyword, which will be added to the list of existing keywords in alphabetical order. AUTOREAD Manual -22- 11.3 Delete ───────────────────────────────────────────────────────────────── This will allow you to get rid of a particular keyword, which you identify from the same pull-down menu as for the Find function. You will be prompted to confirm the delete. 11.4 Search Direction ───────────────────────────────────────────────────────────────── This specifies the current direction of search. The default is DOWN, ie searches on increasing line numbers from the current line. UP searches to decreasing line numbers from the current line. GLOBAL searches from beginning of file. To toggle the direction, simply select this choice. AUTOREAD Manual -23- 12: Marks Menu ══════════════════════════════════════════════════════════════════════ Bookmarks are just like chapter stops - except that they are volatile (they vanish when you exit AUTOREAD), and that they do not have a description, just an ID number and a line number. Bookmarks are intended as quick reference points to 'hold your place' when you are looking for something else in a file. You can only create a maximum of 10 bookmarks. The Marks Menu looks like this: ┌─────────────┐ │ Find F4 │ │ Add Current │ │ Enter │ │ Delete │ └─────────────┘ 12.1 Find (F4) ───────────────────────────────────────────────────────────────── This brings up a menu of the existing bookmarks. You can move the highlight to the wanted bookmark by using the up and down arrow keys. Once you have selected your desired bookmark, press ENTER, and the screen will immediately fill with the text starting at the desired bookmark. 12.2 Add Current ───────────────────────────────────────────────────────────────── This allows you to set the current line (that is, the line currently at the top of the display screen) as a bookmark. You will be prompted for the bookmark number you wish this line to be recorded against. 12.3 Enter ───────────────────────────────────────────────────────────────── This allows you to enter a line number directly for a new bookmark (ie, you don't have to have the display showing that line as the current line). You will be prompted for the bookmark number you wish this line to be recorded against. 12.4 Delete ───────────────────────────────────────────────────────────────── This will allow you to get rid of a particular bookmark, which you identify from the same pull-down menu as for the Find function. AUTOREAD Manual -24- You will be prompted to confirm the delete. 12.3 Function Key Setting & Finding Marks ───────────────────────────────────────────────────────────────── Because bookmarks are mainly used for very rapid access to temporary locations in the file, AUTOREAD allows you to completely bypass the menu system in setting and finding bookmarks. While you are in DISPLAY mode and at a point in the text you wish to return to after looking somewhere else, hold down the SHIFT key and one of the function keys F1..F10. You will hear a warbling sound, indicating that the equivalent bookmark has been set at that point (ie, pressing Shift F2 sets bookmark 2). After you have browsed elsewhere, you can hold down the ALT key and the function key (F1...F10) corresponding to the bookmark you set previously. You will immediately jump back to the place you left. Note that you can use ALT and the function keys to jump to ANY bookmark, whether set with SHIFT + function key or set through the Marks menu. AUTOREAD Manual -25- 13: Find Menu ══════════════════════════════════════════════════════════════════════ The Find Menu looks like this: ┌─────────────────┐ │ Find Text F5 │ │ Last Find: F6 │ │ --------------- │ │ Search DOWN │ └─────────────────┘ 13.1 Find Text (F5) ───────────────────────────────────────────────────────────────── This will prompt you for the text to be found. Once you have entered your desired text, press ENTER, and the screen will begin searching in the indicated direction for the wanted text, putting up a display of the current line number being searched. If the text cannot be found, an error message will appear. Note that unlike the Chapter Make command, Find Text IGNORES the difference between upper and lower case. That is, 'DOS', 'Dos' and 'dos' will all be found by the same keyword choice. Once the wanted text is found, you will be dropped back to Display mode, with the first occurrence of the wanted wanted text on the top line, and all occurrences of the wanted text on the current screen will be highlighted in the current highlight colour. 13.2 Last Find (F6 or ^L) ───────────────────────────────────────────────────────────────── This retains a memory of the last text string you looked for, and enables you to select it again. Otherwise, it works exactly like the Find Text command. Note that finding a keyword is treated as a find-text command, so that Last Find can be used to repeatedly find the same keyword. 13.3 Search Direction ───────────────────────────────────────────────────────────────── This specifies the current direction of search. The default is DOWN, ie searches on increasing line numbers. To toggle the direction, simply select this choice. AUTOREAD Manual -26- 14: Screen Menu ══════════════════════════════════════════════════════════════════════ This menu allows you to alter the foreground colour and background colour of the displayed text. From version 1.08 onwards, this information is now stored in the .ARD file for the current document. The Screen Menu looks like this: ┌────────────────────────┐ │ Foreground WHITE │ │ Background BLUE │ │ Highlights YELLOW │ │ ----------------- │ │ Screen Offset: 0 │ └────────────────────────┘ Note that the current colours are shown on the menu. Once you select the foreground, background or highlight colour, you will be given a pull-down menu of the available colours. Note that the colour change does not take effect until you have pressed ESC to return to the display mode of AUTOREAD. 14.1 Screen Offset ───────────────────────────────────────────────────────────────── This choice has been added in response to requests from users who prefer to see found keywords or chapter headings positioned somewhere other than at the top of the screen. Entering a value of other than zero for the Screen Offset will position the 'current line' that many lines down the displayed screen. Note that the current line is now indicated with a highlighted triangle at the very right of the screen. AUTOREAD Manual -27- 15: Dump Menu ══════════════════════════════════════════════════════════════════════ The Dump Menu looks like this: ┌─────────┐ │ Screen │ │ Chapter │ │ Lines │ └─────────┘ Dump allows you to copy ('dump') parts of the document you are reading either to another file, or to the printer. The choices shown relate to what parts of the document you wish to be dumped. Once you have made this choice, you will be prompted whether you wish to dump to a file or a printer. In the case of a file, you will be asked what file name, and if the file already exists, you will be asked if you wish to append to the end of the file, or to overwrite the existing file (ie, destroy it and start again). 15.1 Screen ───────────────────────────────────────────────────────────────── Choosing this will dump just what you can see on the display screen at the current time, less the top and bottom status lines. 15.2 Chapter ───────────────────────────────────────────────────────────────── This will dump the entire current chapter or section. AUTOREAD will determine the 'current chapter' as the material between the chapter stop prior to the current line number, up to the line before the chapter stop following the current line number. If you position a chapter stop heading as the current line, then dump, you will dump from that heading to just before the next chapter stop heading. NOTE: One side effect is that if you have an alpha-sorted chapter list, AUTOREAD will re-sort it into line order when you make this choice. 15.3 Lines ───────────────────────────────────────────────────────────────── This lets you enter your own start and ending line for the dump. Entering '1' for the first line, and some number larger than the last line in the file will dump the entire document. AUTOREAD Manual -28- 16: To Other Shareware Authors ══════════════════════════════════════════════════════════════════════ It seems to me that AUTOREAD would be an extremely useful program to distribute with your shareware manuals on disk. However, it doesn't seem very fair to the users of your software to be expected to pay a second shareware fee (to me) for the use of AUTOREAD on your manual. For this reason, I will provide a special version of AUTOREAD which will be set up to read only your manual file or files, from the same directory as those files. You will need to pay me a shareware fee of $50 for this special version, and to write to me with the names of the files you want it to be able to read. I will then provide you with the special version. On the other hand, your shareware users will need to pay no additional fee to use AUTOREAD on your manual. You will find it very easy to set up the customised version of AUTOREAD to work with your manual, establishing chapter stops and appropriate keywords, so that your users will find your on-disk manual a truly easy-to-use and valuable reference. However, if you do not want to set up the appropriate chapter stops and keywords yourself, for an additional $30, if you supply me with a copy of your manual, I will establish the appropriate chapter stops and keywords and return the appropriate files to you. AUTOREAD Manual -29- 17: Acknowledgements ══════════════════════════════════════════════════════════════════════ AUTOREAD was written using Borland's Turbo Pascal 5.5, a great compiler which goes on getting better and better, and making me less and less keen to move to programming in C. I used QEDIT Advanced 2.08 from SEMWARE as my text editor during programming and for some of this manual. I've also mentioned QEDIT in a number of places in this manual, to illustrate how AUTOREAD can be used to make access to a large text file manual easy, and I hope SEMWARE didn't mind me doing so! QEDIT is the best text editor I have ever used, and spoils you for all others. It is shareware, and I recommend you write to SEMWARE at 730 Elk Cove Court, Kennesaw, Ga, USA for their current prices. Most of this manual was written using PC-Outline from Brown Bag Software, also shareware, and a program I use intensively for manuals, reports, etc, where section numbering and renumbering is required. Write to Brown Bag Software, PO Box 60000, San Francisco, CA 94160-1719, USA for current prices. Thanks to Don Avila and Russell Herman for reporting bugs and suggesting improvements to AUTOREAD. AUTOREAD Manual -30- 18: Version History ══════════════════════════════════════════════════════════════════════ This is version 1.08 of AUTOREAD. There may still be a few bugs in it. I would be grateful if those who find such bugs could let me know. Similarly, if you have any ideas for ways of improving the product, please let me know. 18.1 Updates ───────────────────────────────────────────────────────────────── 1.01 : (2 July 1990) - GLOBAL search direction added - fix to bug allowing line 0 to be displayed in status - fix to bug involving embedded '/' char in chapter description 1.02 : (5 July 1990) - added highlighting of keywords and found text - changed index file extent from .IDX to .ARI 1.03 : (6 July 1990) - added procedural make. - support for 43-line and 50-line screens. - added alpha sort for chapters - added stand-alone make utility 1.04 : (14 July 1990) - added F1 function key for Help - added F5 function key for Last Find - added F6 function key for Jump to Next Chapter Stop - fixed Upper/Lower case problem with highlighting - fixed bug with files of longer than 32k lines - added Crawl Read 1.05 : (23 July 1990) - added UpperCase make and set up Make sub-menu - increased maximum chapter stops and keywords to 500 1.06 : (1 August 1990) - added F7 function for instant Add Chapter - added Page Find function 1.07 : (6 August 1990) - added Dump function - added F5 for Find Text, rearranged other function keys 1.08 : (20 September 1990) - fixed bug preventing last line of file being seen - added saving of screen colours to .ARD file - added screen offset feature - improved indexing procedure - added Alt-Q - Quit Without Data Save - added Remove Duplicates to Chapter Menu AUTOREAD Manual -31- 18.2 Planned Enhancements ───────────────────────────────────────────────────────────────── In future, I plan to add the following features to AUTOREAD: * Auto-capture of keywords. * Mouse operation. AUTOREAD Manual -32- APPENDIX A: FUNCTION KEY SUMMARY ══════════════════════════════════════════════════════════════════════════ ESC: Toggle AUTOREAD menu bar 0..9: Scroll up steadily (0 for slowest,9 for fastest) F1: Help F2: Chapter Find Alt-C F3: Keyword Find Alt-K F4: Bookmark Find Alt-M F5: Text Find Alt-F F6: Repeat Last Keyword or Text Find Alt-L F7: Add Chapter Stop (no prompts) Alt-A F8: Jump to Next Chapter Heading Alt-J Alt-X: Quit with Data Save Alt-Q: Quit with No Data Save Shift-F1 thru : Set Corresponding Bookmark Shift-F10 Alt-F1 thru : Jump to Corresponding Bookmark Alt-F10 AUTOREAD Manual -33- APPENDIX B: COMMAND-LINE OPTIONS ══════════════════════════════════════════════════════════════════════════ To use a command-line option, append the desired option (which must begin with a hyphen) to the command line you use to start up AUTOREAD, eg: AUTOREAD MANUAL.DOC -Q -B There are currently three command-line options, described below. -B: Forces AUTOREAD to start up with a black-and-white screen display. Useful for LCD screens and monochrome screens. -Q: Prevents AUTOREAD from trying to access or to write an .ARD file for the document, and ensures that AUTOREAD erases the .ARI (if it needed to create it) at the end. This option is intended for quick access to small text files that you don't wish to establish chapter stops and keywords for. -Lnnn: Where nnn is a line number, eg -L123 Forces AUTOREAD to use the given line number as its current line number for its first display, ie it overrides the current line number given in the .ARD file. AUTOREAD Manual -34- APPENDIX C: THE .ARD FILE FORMAT ══════════════════════════════════════════════════════════════════════════ It's often worthwhile using a text editor directly on the .ARD file in order to tidy things up, quickly remove invalid chapter stops which were created by Make, and so on. You can also capture the index pages of the original document and massage them into a list of keywords, which you can directly append to the .ARD file. The .ARD file is just an ordinary text file. The following applies to Version 1.08 of the software: The first line of the .ARD file is in the form: 125/20/1254/15/1/14 In order, these numbers represent: 1) the number of chapter stops (maximum of 500); 2) the number of keywords (ditto) 3) the current line number in the document when you left off reading it. 4) the text colour 5) the background colour 6) the highlight colour Subsequent lines (2..number of chapter stops+1) are in the following format: 1.0 INTRODUCTION/25 The text is of course the chapter description text (max 40 chars), and the number following the slash is the line number where the chapter begins. After the chapter stops, the keywords are simply listed in alphabetical order, eg: Apple Banana Carrot Note that AUTOREAD will always reorder chapter stops in order of line number and keywords in alphabetical order, should you change the order in the .ARD file. The last two lines of the .ARD file specify the Odd and then Even page numbering templates, in the form: MyManual p./69 MyManual/12 where the text before the slash is the text that AUTOREAD uses to check that it has found a page numbering line, and the number after the slash is the column number near where AUTOREAD will check for the wanted page number in the page numbering line. If no page templates has been set, then these numbers will be -1 for both odd and even pages. If you want to manipulate the .ARD file, feel free to do so. Remember, though, that you must amend the first line to reflect any altered numbers of chapter stops and keywords. AUTOREAD Manual -35- APPENDIX D: LIMITATIONS OF AUTOREAD ══════════════════════════════════════════════════════════════════════════ AUTOREAD, like most things, is not perfect. It has limitations. The most important of these is that AUTOREAD will choke if you feed it a file which is too big. Versions 1.01 thru 1.03 could handle files of up to 32,768 lines in length. Version 1.04 onwards now handle files of twice this size, up to 65,536 lines in length. A typical text file of this length would be over 2 MB in size on the disk, so in practice this should not be a severe limitation. You can create a maximum of 500 chapter stops and 500 keywords. AUTOREAD also has no way of determining if a file you are trying to use it on is in fact a text file. It will do very wierd things if you use it on a binary file such as an .EXE file, for example. If you need to examine binary files, use the Norton Utilities or LIST. AUTOREAD will also get very confused if you feed it files with very long lines. While (in the current version) you only get to see the first 79 characters on the line, AUTOREAD can at least handle without confusion files which include lines of up to 255 characters. Any more than that, and AUTOREAD loses track of the beginnings of lines. AUTOREAD Manual -36- APPENDIX E: MUSINGS ON THE WRITING OF MANUALS ══════════════════════════════════════════════════════════════════════════ I guess I was naive when I first set out to create AUTOREAD. I figured that most text file manuals would follow a similar sort of format. Alas! It is now clear that there are as many styles of manual as there are authors. This makes creating a utility like this one which will be able to do such stuff as automatically creating chapter stops very difficult. It amazes me that some authors create manuals where the section headings are barely given ANY kind of distinction from the rest of the body text. No underlinings, no section numberings, not even all in caps. Surely this makes these manuals difficult to read even in a hard copy printout? The same goes (in spades) for different ways of indicating page numbers. I guess this is a (selfish) plea for well designed manuals that AUTOREAD will work well with!